Aminet 51

home *** CD-ROM | disk | FTP | other *** search

/ Aminet 51 / Aminet 51 (2002)(GTI - Schatztruhe)[!][Oct 2002].iso / Aminet / util / arc / xadmasterdev.lha / xad / Include / Autodocs / xadsub.doc < prev

Wrap

Text File | 2002-08-20 | 19.0 KB | 407 lines

TABLE OF CONTENTS xadForeman/--Overview-- xadClient/--Overview-- xadClient/xcFree xadClient/xcGetInfo xadClient/xcRecogData xadClient/xcUnArchive VERSION $VER: xadsub.doc 12.0 (15.06.2002) by SDI xadForeman/--Overview-- xadForeman/--Overview-- The xadForeman structure is just some kind of header for external clients. It protects the clients from being executed accidentally by having a small piece of code (MOVEQ #-1,d0 : RTS) in the first 4 bytes. The master can identify a valid bunch of external clients by checking the first hunk of a file for the foreman identification. Finally, a foreman holds the pointer to a linked list of clients and thus enables the master to work with these clients. The version entry of this structure specifies name and version of the file and not of the linked client list! Multiple clients can be stored in the linked list of one file. This allows to use code by different clients. E.g. The normal archive and a SFX client both use nearly equal unarchiving code, but different recognition functions. If the clients have no double useable code, it is better to distribute them in seperate files to allow better updating. xadClient/--Overview-- xadClient/--Overview-- The xadClient structure is the heart of the whole library system. Each client enables the master to recognize and unarchive files. Therefore each client contains 4 routines that are called from the master. Pointers to these are stored in xc_RecogData, xc_GetInfo, xc_UnArchive and xc_Free. All routines have one thing in common: the CPU registers D0/D1/A0/A1 are so-called scratch registers, they may change during execution, all other registers must remain unchanged. CPU register A6 holds a pointer to the xadMasterBase structure. See chapters below for a description of the client routines. ALL CLIENT ROUTINES MUST BE REENTRANT! NEVER STORE ANY DATA IN STATIC MEMORY AREAS, USE THE STACK OR SOME ALLOCATED MEMORY INSTEAD! REMEMBER THAT THE ROUTINES MIGHT BE CALLED BY SEVERAL PROGRAMS AT THE SAME TIME! DO NOT EXCEED STACK USAGE (1KB SHOULD BE THE MAXIMUM), AS PROGRAMS NORMALLY HAVE ONLY 4KB STACK. The name of the archiver that is supported by the client and the flags that describe the packer are stored in xc_ArchiverName and xc_Flags. Internal clients all have an unique ID value stored in xc_Identifier. If you have written a client that should replace an internal one, because it is faster or otherwise enhanced, simply put the ID of the client to be replaced in xc_Identifier. The old client will then be taken out of the list of used clients. Normally this ID should be zero. There is one problem with this: When the user deactivates external clients the xadmaster system is missing this type completely as internal client is not activated in this case. xcRecogData() usually only requires a quite small part of a file to recognize it properly. To avoid reading the whole file for recognition purposes, you need to set xc_RecogSize to the minimum amount of bytes that is required to recognize the crunched file correctly. Note that xadmaster uses this value internally to decide whether a file might be archived with a archiver or not, so you don't have to do an extra size comparison in your xc_RecogData function any more. For archiver headers with non-constant sizes, simply set xc_RecogSize to a value that will ensure correct recognition of all possible files. Whenever you intend to use features of the xadmaster.library in your clients that are marked (V2) or higher, make sure to set xc_MasterVersion to the desired version number, otherwise an old library version might crash while using the new client. Whenever a client calls a xadmaster function and gets a return code, the client needs to return this code! So whenever an error code is produced somewhere, it must reach the calling program. This is most important for progress report (automatically called by xadHookAccess), as the XADERR_SKIP can be checked by calling program. ANY needed structure must be allocated with xadAllocObject! None of the XAD structures can be allocated any other way! Multivolume support: This system also supports multivolume archives. A special multivolume input stream (XAD_INSPLITTED) allows to pass multiple input files as one stream to the clients. This means multivolume archiver files are passed as ONE stream to the related client. The client may check the ai->xai_MultiVolume entry. This is an ULONG array witch holds the start offset of every part and is finished with an zero value. Note that the first entry is a zero value as well in normal case. The client may expect the parts to be in correct order, but must handle missing or defective parts (Handling of defective archives is necessary for normal archives as well!). Do not rely to much on part size information, as missing parts or defective parts normally will destroy the usefulness of that size information. Filesystem clients: Starting with (V5), the library supports external filesystem clients as well. These clients have no xc_RecogData function, but get called xc_GetInfo always. The fields xc_RecogSize is useless as well for these clients. Filesystem clients are called, when xadGetDiskInfo() and xadDiskFileUnArc() are called. They are skipped for xadGetInfo(). The functions are equal to normal clients, except that they handle filesystem images and no file archives. Apple Macintosh support: When handling special Apple archives, handle data and resource fork as separate entries into xadFileInfo list, with some additional information. The flag XADFIF_MACDATA flag implies: - This file IS a data fork. - This file CAN have a separate resource fork. - This file's xfi_Comment (if not NULL) can be read as "TYPE/CRTR" or "TYPE/CRTR FLGS", where TYPE and CRTR are 4 character ASCII codes detailing a file's file ID and creator ID, and FLGS is a 4 digit hexadecimal number detailing Finder Flags, as defined by the field 'FInfo.fdFlags' in RFC 1740. Any normal comment may be appended at the end seperated by a space character. Use "????/???? 0000" as default in case the data is not available, but a comment needs to be stored. - The entry xfi_MacFork is either NULL or a pointer to the resource fork list entry. The flag XADFIF_MACRESOURCE flag implies: - This file IS a resource fork. - Suggested filename is "<datafork name>.rsrc". - This file DOES have a separate data fork. - The entry xfi_MacFork is a pointer to the data fork list entry. - If the data fork is empty, do not create an entry for it, but leave xfi_MacFork empty and store the comment in resource fork entry. NOTE: The pointer xfi_MacFork points to a normal entry of the file information list! This pointer is only additional information to find corresponding entries. Specials support: Starting with (V11) the xadFileInfo structure has an additional xadSpecial field, which is a linked list of special structures. These can be used to store additional information. Currently this is defined for UNIX devices and Amiga address crunchers. This special structure is defined as "union". The field xfis_Type is used to determine, which structure is really used. That method was choosen to be flexible without removing the advantages of C programming languages. Also the xfi_FileType field is used to supply additional information about the type of the file. This can be useful for extractor programs knowing how to handle special filetypes. xadClient/xcFree xadClient/xcFree NAME xcFree -- Free all resources allocated by xcGetInfo SYNOPSIS xcFree(ai, xadMasterBase) A0 A6 void xcFree(struct xadArchiveInfo *, struct xadMasterBase *) FUNCTION This function frees all the stuff allocated by xcGetInfo. It is called after unsuccessful xcGetInfo as well (except for filesystem clients returning XADERR_FILESYSTEM), so you need not to call any freeing functions there. But be prepared for that case. You must check all entries, as xcGetInfo may fail in the first allocation stages (f.e. allocation of xadDiskInfo or xadFileInfo structures). Clear all entries you have freed! There should not be any pointers left in xadArchiveInfo structure which do not point to valid memory. Starting with (V2) the master library can do some stuff for you. This is always done after calling this function, so you have the chance to do private stuff before! If you set the flag XADCF_FREEFILEINFO in xc_Flags, the master library parses the xai_FileInfo list and frees every entry. If you set the flag XADCF_FREEDISKINFO in xc_Flags, the master library parses the xai_DiskInfo list and frees every entry. If you set the flag XADCF_FREETEXTINFO in xc_Flags, the master library parses the xdi_TextInfo list of every xadDiskInfo structure and frees every entry. If you set the flag XADCF_FREETEXTINFOTEXT in xc_Flags, the master library frees xti_Text entry of xadTextInfo structures. This requires these entries to be allocated with xadAllocVec() function. If you set the flag XADCF_FREESKIPINFO with (V3) in xc_Flags, the master library parses the xai_SkipInfo list and frees every entry. If you set the flag XADCF_FREEPECIALINFO with (V11) in xc_Flags, the master library parses the xfi_SpecialInfo list and frees every entry. If you set the flag XADCF_FREEXADSTRINGS with (V12) in xc_Flags, the master library parses the xadFileInfo structures and frees every entry, which is marked as XAD string. If your free function is empty, because all can be done by master library, then you may place a zero in xc_Free field of xadClient structure and remove the function totally. INPUTS ai the master communication structure SEE ALSO Example sourcecodes, xadmaster.library/xadFreeInfo() xadClient/xcGetInfo xadClient/xcGetInfo NAME xcGetInfo -- create all information about an archive file SYNOPSIS result = xcGetInfo(ai, xadMasterBase) D0 A0 A6 LONG xcGetInfo(struct xadArchiveInfo *, struct xadMasterBase *) FUNCTION This function is the most important one. It creates a structure list containing all necessary information. File archivers create a linked list of xadFileInfo structures for every file/link/ directory which is stored in the archive. xadAllocObject helps to store that information by providing 3 tags for getting special memory. XAD_OBJNAMESIZE can be used to allocate a buffer for storing (also multiple) names. The buffer is byte aligned. Do not forget to count the 0-byte for every string you want to store there. The buffer pointer is stored in xfi_FileName. XAD_OBJCOMMENTSIZE is equal to this, but stored in xfi_Comment. For file and disk archives there is the flag XAD_OBJPRIVINFOSIZE, which returns a longword aligned buffer in xfi_PrivateInfo or xdi_PrivateInfo. Disk archivers create a linked list of xadDiskInfo structures. Normal disk archivers do not allow to store more than one archive, so linking is most time not necessary, but it is supported. When storing information texts, they must be finished with a zero byte, which is not counted in size field! Starting with (V12) a new handling of filename, comment and linkname is possible. The function xadGetFilename() can be used the convert the names from different charsets and encodings and create and allocate an XAD string. When using this the flags XADFIF_XADSTRFILENAME, XADFIF_XADSTRLINKNAME and XADFIF_XADSTRCOMMENT need to be set and it makes no sense to use the XAD_OBJ...SIZE tags with the structure allocation. If the client structure has XADCF_FREEXADSTRINGS set, these strings are freed automatically later. Always use this method instead of doing own conversions, as the XAD strings are loseless (by using unicode internally). The destination type for xadGetFilename() must be CHARSET_HOST always! Every file or disk entry gets an entrynumber, which must be unique. The number for each entry must be exactly the same, if the archive is reopened. Most disk archivers are based on cylinder structure. These should fill the xadDiskInfo fields correctly. If archivers are not based on it (e.g. only sector based) they need to set XADDIF_NOCYLINDER flag! Starting with (V10) the functions xadAddFileEntry() and xadAddDiskEntry() should be used to insert a new entry into the linked list. This allows to use progress hooks and automatically sets correct entry number. Always use the return value, as it may be XADERR_BREAK, if user stopped processing! If possible the EXTRACTONBUILD flags can be set and the entry maybe extracted directly after adding it. The XAD_SETINPOS flag is useful to get correct file position in any case. If the archiver format does not support file dates, set the current date (XAD_DATECURRENTTIME tag) and XADFIF_NODATE flag. Protection bits default to zero (equals "rwed"). Archivers may store XADAIF_FILECORRUPT flag in xai_Flags, when archive is corrupt, but some entries are still usable. Unusable entries must not appear in entry list. Do not return an error code in that case, as an error code always means total failure. Starting with V2, an error code may be stored in xai_LastError, when XADAIF_FILECORRUPT is used. Starting with (V3), you may produce a linked list of xadSkipInfo structures. The entries must not overlap and there must be at least one byte between entries! This forces the xadHookTagAccess() function to skip these parts for read, copy and input seek operations, when XAD_USESKIPINFO tag is used. The system can handle single crunched files also. These are handled as if they where file archives. Set XADFIF_NOFILENAME or XADFIF_NOUNCRUNCHSIZE if necessary. In case you set XADFIF_NOFILENAME, you should store xadMasterBase->xmb_DefaultName as filename. Starting with V7 the master library supplies the input name in xai_InName (only if available). This can be used for name creation also. You need to allocate name space and copy (and modify) that name, as the pointer does not stay valid after leaving xcGetInfo(). Filesystem clients need to return XADERR_FILESYSTEM, if the type is totally unknown. Else they will break the scanning for other filesystems. Do not return any other return codes (except produced by low memory or input errors), before you have validated the file type. NOTE: When XADERR_FILESYSTEM is returned, you may not allocate any stuff or change any pointers or entries in the archiveinfo structure. Especially the xcFree() functions is not called in this case! If you do any allocations, so free them before leaving the function with XADERR_FILESYSTEM. INPUTS ai master communication structure RESULT result - any of the XADERR codes or zero when all is ok. SEE ALSO Example sourcecodes, xadmaster.library/xadGetInfo(), xadmaster.library/xadHookTagAccess(), xadmaster.library/xadHookAccess(), xadmaster.library/xadGetFilename(), xadmaster.library/xadAddFileEntry(), xadmaster.library/xadAddDiskEntry() xadClient/xcRecogData xadClient/xcRecogData NAME xcRecogData -- Scan input buffer for known archiver type SYNOPSIS result = xcRecogData(size, buffer, xadMasterBase) D0 D0 A0 A6 BOOL xcRecogData(ULONG, STRPTR, struct xadMasterBase *) FUNCTION Returns non zero when this buffer is part of a archive file supported by this client. The recognition should be very stable. It should be tested with lots of files. One wrong recognition for 100000 files is acceptable. The minimum size needed for recognition (stored in xadClient structure) should not be larger than 1024 bytes if possible. Remember, that the master library needs to allocate recognition buffers with largest size found in all clients. Scanning archives is slowed down, if this size is too large! This function does not exists for filesystem clients (set its pointer to 0). If you set XADCF_NOCHECKSIZE in client structure, this function is also called for buffers shorter than the minimum size specified in client structure. This is useful for archiver formats, which have different sizes and hard detection schemes (e.g. EXE and SFX types). You need to do minimum checks yourself: The minimum passed size may be zero (empty file!). Do not read behind buffer borders in any case. INPUTS size size of passed buffer buffer buffer containing start of file to scan RESULT result - TRUE if archiver is recogniced, FALSE if not SEE ALSO Example sourcecodes, xadmaster.library/xadRecogFile(), xadmaster.library/xadGetInfo() xadClient/xcUnArchive xadClient/xcUnArchive NAME xcUnArchive -- write the required entry to destination SYNOPSIS result = xcUnArchive(ai, xadMasterBase) D0 A0 A6 LONG xcUnArchive(struct xadArchiveInfo *, struct xadMasterBase *) FUNCTION This function dearchives one entry. The required entry is passed in xai_CurFile or xai_CurDisk. A normal client will support only one of the two possibilities, but clients using file and/or disk archives are allowed as well. When writing disk data, the client should write data in blocks with size of multiple sectorsize. Although it should work, it is not recommended to write blocks unequal to this. Nearly all information you may need is stored in xadArchiveInfo structure. You may expect the entries to be unarchived in same order as they are numbered, but it is not necessary! So be prepared to restart decrunching for archivers using blocks or merge methods. Disk archivers may expect to be called again to dearchive an entry, even if there is only one! So restore the file position you need to unarchive. When XADFIF_SEEKDATAPOS (file archive) or XADDIF_SEEKDATAPOS (disk archive) is set, the master automatically seeks to the position in xfi_DataPos or xdi_DataPos (V3). Starting with (V3), a linked list of xadSkipInfo structures forces the xadHookTagAccess() function to skip these parts for read, copy and input seek operations, when XAD_USESKIPINFO tag is used. INPUTS ai master communication structure RESULT result - any of the XADERR codes or zero when all is ok. SEE ALSO Example sourcecodes, xadmaster.library/xadDiskunArc(), xadmaster.library/xadFileUnArc()